home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 201-225 / disk_221 / iffm2 / iffm2.doc < prev    next >
Text File  |  1992-05-06  |  10KB  |  218 lines
  1.  
  2.              IIIIIIII FFFFFFFF FFFFFFFF  MM      MMM  222222
  3.                 II    FF       FF       MMMM    MMMM 22    22
  4.                 II    FF       FF      MM  MM  MM MM      222
  5.                 II    FFFFFF   FFFFFF MM    MMMM  MM    222
  6.                 II    FF       FF    MM      MM   MM  222
  7.                 II    FF       FF   MM            MM 22
  8.              IIIIIIII FF       FF  MM             MM 22222222
  9.  
  10.                  M2Amiga (tm) Modula-2 IFF Support Module
  11.                      V1.0.0D for M2Amiga (tm) Rel 3.1
  12.                
  13.                Copyright (c) 1988, 1989  Second Sight (tm)
  14.                
  15.                          Developed by Greg Epley
  16.  
  17.  
  18. Introduction
  19. ~~~~~~~~~~~~
  20. IFF files are organized in a basic manner and if this basic organization
  21. doesn't exist the resulting file is not good for much of anything anyway.
  22. It is with this principle in mind that we present IFF support for Interface
  23. Technologies M2Amiga (tm) Modula-2 system.
  24.  
  25. This support bears little resemblance to Electronic Arts IFF-85 standard
  26. routines for reading/writing IFF files, since this would greatly increase
  27. the size of the support modules and also make them needlessly complicated
  28. to use.  The routines do follow the standards outlined in the IFF-85
  29. standards published by Commodore-Amiga in cooperation with Electronic Arts,
  30. and they will also take into account changes that occur as the standards are
  31. refined.
  32.  
  33. To keep the system simple it will all be contained within a single support
  34. module, which is NOT user expandable.  The primary reason for this is so
  35. that we can maintain control and order over the system.  A user expandable
  36. system would be nice but not very efficient in the long run since users
  37. would be expanding it in different ways.  The only way that we can maintain
  38. that order is to keep the system source private so it CANNOT be altered.
  39. The only exception to this might be the very knowledgable assembly language
  40. "hacker" or some other unscrupulous individual who seeks to make life
  41. unpleasant for everyone.
  42.  
  43. Please understand that we are not trying to monopolize IFF support for the
  44. M2Amiga (tm) system by maintaining such control.  The upgrade fee for future
  45. enhancements to the module will be reasonable unless the system is pirated
  46. by individuals such as those mentioned above; in that event we will probably
  47. suspend any future releases but we will continue to support any problems
  48. with the current release at that time.  Let's hope it doesn't come to that.
  49.  
  50. The first priority is ILBM support, following with 8SVX, then SMUS and/or
  51. ANIM (whichever seems to be needed first).
  52.  
  53.  
  54. Demo
  55. ~~~~
  56. The files you have with this document are for demonstration purposes only,
  57. and provide ILBM (InterLeaved BitMap) file reading routines.  If you like
  58. what you see here we urge you to purchase the complete IFFM2 system modules
  59. which currently offer reading and writing of ILBM files.  See "Purchasing"
  60. below for more information.
  61.  
  62.  
  63. Installation
  64. ~~~~~~~~~~~~
  65. 1.    You should have the following four files to use the system:
  66.  
  67.       o IFFM2.sym
  68.       o IFFM2.obj
  69.         o IFFM2.def
  70.       o IFFM2.doc
  71.         
  72.         In addition, you should also have the accessory files:
  73.         
  74.         o ViewILBM
  75.         o ViewILBM.mod
  76.  
  77.  
  78. 2.    We assume that programmers have a basic understanding of the CLI
  79.     since it is required from time to time.  If you are not at all
  80.         familiar with the CLI you should seek out assistance from a
  81.         knowledgable friend or contact us for more specific information.
  82.     We also assume that most programmers have at least 2 3.5" floppy
  83.         drives.  If you only have one it will take a few disk swaps to
  84.         install the files; again, we suggest you seek out the assistance
  85.         of a knowledgable friend or contact us for more information.
  86.  
  87.  
  88. 3.    We suggest that you use the CLI to copy the IFFM2.sym file into
  89.     the Modules/Interfaces/sym directory, and the IFFM2.obj file
  90.         into the Modules/Interfaces/obj directory.  You will find it
  91.         helpful to also print out the IFFM2.def file for reference to
  92.         the routines (this file has NOT been specifically formatted to
  93.         page-break; you will have to perform such operations yourself).
  94.  
  95.  
  96. ILBM Support
  97. ~~~~~~~~~~~~
  98. To read an ILBM file you need routines which can:
  99.  
  100.     o Open and Close the file for access.
  101.     o Read the various groups of information (chunks) that the file has.
  102.     o Report errors that occur in text messages to a standard output
  103.       stream.
  104.     o When reading, parse the file for chunks regardless of order.
  105.     o A simple means of passing client declared storage areas to the
  106.       routines for accessing/filling.
  107.  
  108. BMHD, CMAP, BODY, and CAMG are the only supported ILBM chunks at this time.
  109. Addition of CCRT and CRNG color-cycling chunks will come later.  The
  110. cmpByteRun1 decompression provided is at least as fast as the EA IFF-85
  111. standard when used with any style of HAM (Hold-And-Modify) files, but is
  112. anywhere from 1/3 to 1/2 slower when used with some other types of files,
  113. particularly 16-color, hi-res, interlaced (640 x 400).  Overscan files in
  114. any resolutions are about as fast.  We hope to eliminate this problem by
  115. coding the compression/decompression algorithms in assembler at a later
  116. date.
  117.  
  118.  
  119. The IFFFileFrame Structure
  120. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  121. This structure provides areas for all items that currently require some
  122. storage or reference.  By updating this single structure and making a
  123. few additions within the various routines we will be able to easily add
  124. support for new file and chunk types as they appear.  Here is the layout
  125. of this sturcture:
  126.  
  127.     filehandle    - the DOS FileHandlePtr for the file to act upon.
  128.         bmhd        - the BitMapHeaDer (BMHD) data space.
  129.         cmap        - the ColorMAP (CMAP) data space.
  130.         bitmap        - the BitMap (BODY) data space.
  131.         camg        - the Commodore-AMiGa viewmodes data space.
  132.  
  133. In addition, the bmhd and cmap data spaces are structures which have still
  134. more information relating to the data in the file.  All of the parameters
  135. in the supporting routines are totally independent of these, requiring only
  136. the IFFFileFramePtr to the file you wish to act upon.
  137.  
  138.  
  139. Routine Calls
  140. ~~~~~~~~~~~~~
  141. You can find the specific Modula-2 format routine calls and other items of
  142. interest in the IFFM2.def file.  This is the DEFINITION module for IFFM2
  143. support.
  144.  
  145. A sample program, ViewILBM, is included (along with the source), which shows
  146. how to use the reading routines.  It works from both the Workbench and CLI.
  147. From the CLI prompt type:
  148.  
  149.     1> viewilbm <file> [<delay>]    <RETURN>
  150.         
  151. The <delay> parameter is optional.  Omitting it will cause the picture to
  152. stay until you close it.  The <delay> is a number of seconds that you want
  153. the picture to remain on-screen.  <file> is the name of some picture file
  154. that you want to see.  If the picture file has an icon (or you provide an
  155. icon) you can view the file from the Workbench.  There are two ways to do
  156. this:
  157.  
  158.     1.    Single-click on the picture file icon and select "Info"
  159.             from the "Workbench" menu.  Click in the TOOL TYPES box
  160.                 and type "viewilbm" (without the quotes), press <RETURN>,
  161.                 and click on SAVE.  Now you can view that picture by
  162.                 just double-clicking on the picture icon.
  163.                 
  164.         2.    Single-click on the ViewILBM icon, hold down either <SHIFT>
  165.             key, and double-click the picture icon.
  166.  
  167. Regardless of how you view the picture or if you use the <delay> option
  168. from the CLI, you have control over when to stop viewing.  Clicking anywhere
  169. down in the displayed picture will cause a drag bar to appear to let you
  170. move screens about or whatever.  Clicking again anywhere down in the picture
  171. will toggle that bar off.  To end viewing at any time just click in the upper
  172. left corner (where a window's close box would normally be).  Also notice
  173. that your mouse pointer appears when the drag bar appears and disappears at
  174. all other times.
  175.  
  176. ViewILBM is not intended to be a fantastic work of programming art and some
  177. changes have already taken place in the version which is included with the
  178. full IFFM2 supports, though they are minor changes.
  179.  
  180.  
  181. Purchasing
  182. ~~~~~~~~~~
  183. To get the full IFFM2 supports, which will allow you to read and write ILBM
  184. files, select ONE of the item #'s below and send the indicated items to the
  185. address given below (PLEASE include a note with the item # on it for our
  186. records or we can't process your order):
  187.  
  188.     Item #                        Price
  189.         ------------------------------------------------------
  190.         IFF001    Send check only.            $30.00
  191.         IFF002    Send a check, blank disk, and SASM*    $25.00
  192.         
  193. Make checks payable to: Greg Epley.  NC residents please add appropriate
  194. state tax.  Incomplete orders will NOT be processed or returned (including
  195. disks under option 2, unless a SASM is included under option 2, in which
  196. case we will send your blank disk back without any files).
  197.  
  198. Send to:    Second Sight
  199.             306 Arbor Drive
  200.             Lexington, NC  27292
  201.         Attn: Greg Epley
  202.  
  203. Please allow 3 weeks for delivery via US Mail.  Foreign/Canadian orders
  204. should expect an appropriate delay beyond this.
  205.  
  206. If you would like more information contact the developer via modem at:
  207.  
  208.         MEGA-Byte
  209.                 (704) 798-3431
  210.                 1200/2400 baud, 8N1, 24 hrs/day
  211.  
  212. *SASM - Self-Addressed Stamped Mailer
  213.  
  214. ---------------------------------------------------------------------------
  215. Amiga is a registered trademark of Commodore-Amiga, Inc.  Second Sight is a
  216. trademark of Second Sight.  M2Amiga is a trademark of Interface Technologies
  217. and A.+L. Meier-Vogt.
  218.